
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Geolocation with GeoIP2 &#8212; Django 2.2.12.dev20200304094918 documentation</title>
    <link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../../../" src="../../../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../../../genindex.html" />
    <link rel="search" title="Search" href="../../../search.html" />
    <link rel="next" title="GeoDjango Utilities" href="utils.html" />
    <link rel="prev" title="GDAL API" href="gdal.html" />



 
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../../templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);</script>

  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../../index.html">Django 2.2.12.dev20200304094918 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../../index.html">Home</a>  |
        <a title="Table of contents" href="../../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../../genindex.html">Index</a>  |
        <a title="Module index" href="../../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="gdal.html" title="GDAL API">previous</a>
     |
    <a href="../../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="utils.html" title="GeoDjango Utilities">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="ref-contrib-gis-geoip2">
            
  <div class="section" id="s-module-django.contrib.gis.geoip2">
<span id="s-geolocation-with-geoip2"></span><span id="module-django.contrib.gis.geoip2"></span><span id="geolocation-with-geoip2"></span><h1>Geolocation with GeoIP2<a class="headerlink" href="#module-django.contrib.gis.geoip2" title="Permalink to this headline">¶</a></h1>
<p>The <a class="reference internal" href="#django.contrib.gis.geoip2.GeoIP2" title="django.contrib.gis.geoip2.GeoIP2"><code class="xref py py-class docutils literal notranslate"><span class="pre">GeoIP2</span></code></a> object is a wrapper for the <a class="reference external" href="https://geoip2.readthedocs.io/">MaxMind geoip2 Python
library</a>. <a class="footnote-reference" href="#id6" id="id1">[1]</a></p>
<p>In order to perform IP-based geolocation, the <a class="reference internal" href="#django.contrib.gis.geoip2.GeoIP2" title="django.contrib.gis.geoip2.GeoIP2"><code class="xref py py-class docutils literal notranslate"><span class="pre">GeoIP2</span></code></a> object requires
the <a class="reference external" href="https://pypi.org/project/geoip2/">geoip2 Python library</a> and the GeoIP <cite>Country</cite> and/or <cite>City</cite> <a class="reference external" href="https://dev.maxmind.com/geoip/geoip2/geolite2/">datasets
in binary format</a> (the CSV files will not work!). Grab the
<code class="docutils literal notranslate"><span class="pre">GeoLite2-Country.mmdb.gz</span></code> and <code class="docutils literal notranslate"><span class="pre">GeoLite2-City.mmdb.gz</span></code> files and unzip them
in a directory corresponding to the <a class="reference internal" href="#std:setting-GEOIP_PATH"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code></a> setting.</p>
<p>Additionally, it is recommended to install the <a class="reference external" href="https://github.com/maxmind/libmaxminddb">libmaxminddb C library</a>, so
that <code class="docutils literal notranslate"><span class="pre">geoip2</span></code> can leverage the C library’s faster speed.</p>
<div class="section" id="s-example">
<span id="example"></span><h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
<p>Here is an example of its usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django.contrib.gis.geoip2</span> <span class="k">import</span> <span class="n">GeoIP2</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">=</span> <span class="n">GeoIP2</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">country</span><span class="p">(</span><span class="s1">&#39;google.com&#39;</span><span class="p">)</span>
<span class="go">{&#39;country_code&#39;: &#39;US&#39;, &#39;country_name&#39;: &#39;United States&#39;}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">city</span><span class="p">(</span><span class="s1">&#39;72.14.207.99&#39;</span><span class="p">)</span>
<span class="go">{&#39;city&#39;: &#39;Mountain View&#39;,</span>
<span class="go">&#39;continent_code&#39;: &#39;NA&#39;,</span>
<span class="go">&#39;continent_name&#39;: &#39;North America&#39;,</span>
<span class="go">&#39;country_code&#39;: &#39;US&#39;,</span>
<span class="go">&#39;country_name&#39;: &#39;United States&#39;,</span>
<span class="go">&#39;dma_code&#39;: 807,</span>
<span class="go">&#39;latitude&#39;: 37.419200897216797,</span>
<span class="go">&#39;longitude&#39;: -122.05740356445312,</span>
<span class="go">&#39;postal_code&#39;: &#39;94043&#39;,</span>
<span class="go">&#39;region&#39;: &#39;CA&#39;,</span>
<span class="go">&#39;time_zone&#39;: &#39;America/Los_Angeles&#39;}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">lat_lon</span><span class="p">(</span><span class="s1">&#39;salon.com&#39;</span><span class="p">)</span>
<span class="go">(39.0437, -77.4875)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">lon_lat</span><span class="p">(</span><span class="s1">&#39;uh.edu&#39;</span><span class="p">)</span>
<span class="go">(-95.4342, 29.834)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">geos</span><span class="p">(</span><span class="s1">&#39;24.124.1.80&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">wkt</span>
<span class="go">&#39;POINT (-97 38)&#39;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-api-reference">
<span id="api-reference"></span><h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="django.contrib.gis.geoip2.GeoIP2">
<em class="property">class </em><code class="descname">GeoIP2</code>(<em>path=None</em>, <em>cache=0</em>, <em>country=None</em>, <em>city=None</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>The <code class="docutils literal notranslate"><span class="pre">GeoIP</span></code> object does not require any parameters to use the default
settings. However, at the very least the <a class="reference internal" href="#std:setting-GEOIP_PATH"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code></a> setting
should be set with the path of the location of your GeoIP datasets. The
following initialization keywords may be used to customize any of the
defaults.</p>
<table class="docutils">
<colgroup>
<col width="25%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Keyword Arguments</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">path</span></code></td>
<td>Base directory to where GeoIP data is located or the
full path to where the city or country data files
(<code class="docutils literal notranslate"><span class="pre">.mmdb</span></code>) are located. Assumes that both the city and
country datasets are located in this directory;
overrides the <a class="reference internal" href="#std:setting-GEOIP_PATH"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code></a> setting.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">cache</span></code></td>
<td>The cache settings when opening up the GeoIP datasets. May
be an integer in (0, 1, 2, 4, 8) corresponding to the
<code class="docutils literal notranslate"><span class="pre">MODE_AUTO</span></code>, <code class="docutils literal notranslate"><span class="pre">MODE_MMAP_EXT</span></code>, <code class="docutils literal notranslate"><span class="pre">MODE_MMAP</span></code>, and
<code class="docutils literal notranslate"><span class="pre">GEOIP_INDEX_CACHE</span></code> <code class="docutils literal notranslate"><span class="pre">MODE_MEMORY</span></code> C API settings,
respectively. Defaults to 0 (<code class="docutils literal notranslate"><span class="pre">MODE_AUTO</span></code>).</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">country</span></code></td>
<td>The name of the GeoIP country data file. Defaults
to <code class="docutils literal notranslate"><span class="pre">GeoLite2-Country.mmdb</span></code>. Setting this keyword
overrides the <a class="reference internal" href="#std:setting-GEOIP_COUNTRY"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_COUNTRY</span></code></a> setting.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">city</span></code></td>
<td>The name of the GeoIP city data file. Defaults to
<code class="docutils literal notranslate"><span class="pre">GeoLite2-City.mmdb</span></code>. Setting this keyword overrides
the <a class="reference internal" href="#std:setting-GEOIP_CITY"><code class="xref std std-setting docutils literal notranslate"><span class="pre">GEOIP_CITY</span></code></a> setting.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-methods">
<span id="methods"></span><h2>Methods<a class="headerlink" href="#methods" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-instantiating">
<span id="instantiating"></span><h3>Instantiating<a class="headerlink" href="#instantiating" title="Permalink to this headline">¶</a></h3>
<dl class="classmethod">
<dt id="django.contrib.gis.geoip2.GeoIP2.open">
<em class="property">classmethod </em><code class="descclassname">GeoIP2.</code><code class="descname">open</code>(<em>path</em>, <em>cache</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.open" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>This classmethod instantiates the GeoIP object from the given database path
and given cache setting.</p>
</div>
<div class="section" id="s-querying">
<span id="querying"></span><h3>Querying<a class="headerlink" href="#querying" title="Permalink to this headline">¶</a></h3>
<p>All the following querying routines may take either a string IP address
or a fully qualified domain name (FQDN). For example, both
<code class="docutils literal notranslate"><span class="pre">'205.186.163.125'</span></code> and <code class="docutils literal notranslate"><span class="pre">'djangoproject.com'</span></code> would be valid query
parameters.</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.city">
<code class="descclassname">GeoIP2.</code><code class="descname">city</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.city" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Returns a dictionary of city information for the given query. Some
of the values in the dictionary may be undefined (<code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.country">
<code class="descclassname">GeoIP2.</code><code class="descname">country</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.country" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Returns a dictionary with the country code and country for the given
query.</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.country_code">
<code class="descclassname">GeoIP2.</code><code class="descname">country_code</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.country_code" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Returns the country code corresponding to the query.</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.country_name">
<code class="descclassname">GeoIP2.</code><code class="descname">country_name</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.country_name" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Returns the country name corresponding to the query.</p>
</div>
<div class="section" id="s-coordinate-retrieval">
<span id="coordinate-retrieval"></span><h3>Coordinate Retrieval<a class="headerlink" href="#coordinate-retrieval" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.coords">
<code class="descclassname">GeoIP2.</code><code class="descname">coords</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.coords" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Returns a coordinate tuple of (longitude, latitude).</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.lon_lat">
<code class="descclassname">GeoIP2.</code><code class="descname">lon_lat</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.lon_lat" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Returns a coordinate tuple of (longitude, latitude).</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.lat_lon">
<code class="descclassname">GeoIP2.</code><code class="descname">lat_lon</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.lat_lon" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Returns a coordinate tuple of (latitude, longitude),</p>
<dl class="method">
<dt id="django.contrib.gis.geoip2.GeoIP2.geos">
<code class="descclassname">GeoIP2.</code><code class="descname">geos</code>(<em>query</em>)<a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2.geos" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Returns a <a class="reference internal" href="geos.html#django.contrib.gis.geos.Point" title="django.contrib.gis.geos.Point"><code class="xref py py-class docutils literal notranslate"><span class="pre">Point</span></code></a> object corresponding to the
query.</p>
</div>
</div>
<div class="section" id="s-settings">
<span id="settings"></span><h2>Settings<a class="headerlink" href="#settings" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-geoip-path">
<span id="s-std:setting-GEOIP_PATH"></span><span id="geoip-path"></span><span id="std:setting-GEOIP_PATH"></span><h3><code class="docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code><a class="headerlink" href="#geoip-path" title="Permalink to this headline">¶</a></h3>
<p>A string specifying the directory where the GeoIP data files are
located. This setting is <em>required</em> unless manually specified
with <code class="docutils literal notranslate"><span class="pre">path</span></code> keyword when initializing the <a class="reference internal" href="#django.contrib.gis.geoip2.GeoIP2" title="django.contrib.gis.geoip2.GeoIP2"><code class="xref py py-class docutils literal notranslate"><span class="pre">GeoIP2</span></code></a> object.</p>
</div>
<div class="section" id="s-geoip-country">
<span id="s-std:setting-GEOIP_COUNTRY"></span><span id="geoip-country"></span><span id="std:setting-GEOIP_COUNTRY"></span><h3><code class="docutils literal notranslate"><span class="pre">GEOIP_COUNTRY</span></code><a class="headerlink" href="#geoip-country" title="Permalink to this headline">¶</a></h3>
<p>The basename to use for the GeoIP country data file. Defaults to
<code class="docutils literal notranslate"><span class="pre">'GeoLite2-Country.mmdb'</span></code>.</p>
</div>
<div class="section" id="s-geoip-city">
<span id="s-std:setting-GEOIP_CITY"></span><span id="geoip-city"></span><span id="std:setting-GEOIP_CITY"></span><h3><code class="docutils literal notranslate"><span class="pre">GEOIP_CITY</span></code><a class="headerlink" href="#geoip-city" title="Permalink to this headline">¶</a></h3>
<p>The basename to use for the GeoIP city data file. Defaults to
<code class="docutils literal notranslate"><span class="pre">'GeoLite2-City.mmdb'</span></code>.</p>
</div>
</div>
<div class="section" id="s-exceptions">
<span id="exceptions"></span><h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h2>
<dl class="exception">
<dt id="django.contrib.gis.geoip2.GeoIP2Exception">
<em class="property">exception </em><code class="descname">GeoIP2Exception</code><a class="headerlink" href="#django.contrib.gis.geoip2.GeoIP2Exception" title="Permalink to this definition">¶</a></dt>
<dd><p>The exception raised when an error occurs in a call to the underlying
<code class="docutils literal notranslate"><span class="pre">geoip2</span></code> library.</p>
</dd></dl>

<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>GeoIP(R) is a registered trademark of MaxMind, Inc.</td></tr>
</tbody>
</table>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Geolocation with GeoIP2</a><ul>
<li><a class="reference internal" href="#example">Example</a></li>
<li><a class="reference internal" href="#api-reference">API Reference</a></li>
<li><a class="reference internal" href="#methods">Methods</a><ul>
<li><a class="reference internal" href="#instantiating">Instantiating</a></li>
<li><a class="reference internal" href="#querying">Querying</a></li>
<li><a class="reference internal" href="#coordinate-retrieval">Coordinate Retrieval</a></li>
</ul>
</li>
<li><a class="reference internal" href="#settings">Settings</a><ul>
<li><a class="reference internal" href="#geoip-path"><code class="docutils literal notranslate"><span class="pre">GEOIP_PATH</span></code></a></li>
<li><a class="reference internal" href="#geoip-country"><code class="docutils literal notranslate"><span class="pre">GEOIP_COUNTRY</span></code></a></li>
<li><a class="reference internal" href="#geoip-city"><code class="docutils literal notranslate"><span class="pre">GEOIP_CITY</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="gdal.html"
                        title="previous chapter">GDAL API</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="utils.html"
                        title="next chapter">GeoDjango Utilities</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../../../_sources/ref/contrib/gis/geoip2.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Mar 04, 2020</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="gdal.html" title="GDAL API">previous</a>
     |
    <a href="../../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="utils.html" title="GeoDjango Utilities">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>